home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat2 / standard / putmsg.z / putmsg
Encoding:
Text File  |  2002-10-03  |  13.4 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ppppuuuuttttmmmmssssgggg((((2222))))                                                            ppppuuuuttttmmmmssssgggg((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _pppp_uuuu_tttt_mmmm_ssss_gggg - send a message on a stream
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_rrrr_oooo_pppp_tttt_ssss_...._hhhh_>>>>
  13.  
  14.      _iiii_nnnn_tttt _pppp_uuuu_tttt_mmmm_ssss_gggg_((((_iiii_nnnn_tttt _ffff_dddd_,,,, _cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_bbbb_uuuu_ffff _****_cccc_tttt_llll_pppp_tttt_rrrr_,,,,
  15.                 _cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_bbbb_uuuu_ffff _****_dddd_aaaa_tttt_aaaa_pppp_tttt_rrrr_,,,, _iiii_nnnn_tttt _ffff_llll_aaaa_gggg_ssss_))))_;;;;
  16.  
  17.      _iiii_nnnn_tttt _pppp_uuuu_tttt_pppp_mmmm_ssss_gggg_((((_iiii_nnnn_tttt _ffff_dddd_,,,, _cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_bbbb_uuuu_ffff _****_cccc_tttt_llll_pppp_tttt_rrrr_,,,,
  18.                 _cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_bbbb_uuuu_ffff _****_dddd_aaaa_tttt_aaaa_pppp_tttt_rrrr_,,,, _iiii_nnnn_tttt _bbbb_aaaa_nnnn_dddd_,,,, _iiii_nnnn_tttt _ffff_llll_aaaa_gggg_ssss_))))_;;;;
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      _pppp_uuuu_tttt_mmmm_ssss_gggg creates a message from user-specified buffer(s) and sends the
  22.      message to a STREAMS file.  The message may contain either a data part, a
  23.      control part, or both.  The data and control parts to be sent are
  24.      distinguished by placement in separate buffers, as described below.  The
  25.      semantics of each part is defined by the STREAMS module that receives the
  26.      message.
  27.  
  28.      The function _pppp_uuuu_tttt_pppp_mmmm_ssss_gggg does the same thing as _pppp_uuuu_tttt_mmmm_ssss_gggg, but provides the user
  29.      the ability to send messages in different priority bands.  Except where
  30.      noted, all information pertaining to _pppp_uuuu_tttt_mmmm_ssss_gggg also pertains to _pppp_uuuu_tttt_pppp_mmmm_ssss_gggg.
  31.  
  32.      _f_d specifies a file descriptor referencing an open stream.  _c_t_l_p_t_r and
  33.      _d_a_t_a_p_t_r each point to a _ssss_tttt_rrrr_bbbb_uuuu_ffff structure, which contains the following
  34.      members:
  35.  
  36.           _iiii_nnnn_tttt _mmmm_aaaa_xxxx_llll_eeee_nnnn_;;;;     _////_**** _nnnn_oooo_tttt _uuuu_ssss_eeee_dddd _****_////
  37.           _iiii_nnnn_tttt _llll_eeee_nnnn_;;;;        _////_**** _llll_eeee_nnnn_gggg_tttt_hhhh _oooo_ffff _dddd_aaaa_tttt_aaaa _****_////
  38.           _vvvv_oooo_iiii_dddd _****_bbbb_uuuu_ffff_;;;;      _////_**** _pppp_tttt_rrrr _tttt_oooo _bbbb_uuuu_ffff_ffff_eeee_rrrr _****_////
  39.  
  40.      _c_t_l_p_t_r points to the structure describing the control part, if any, to be
  41.      included in the message.  The _bbbb_uuuu_ffff field in the _ssss_tttt_rrrr_bbbb_uuuu_ffff structure points to
  42.      the buffer where the control information resides, and the _llll_eeee_nnnn field
  43.      indicates the number of bytes to be sent.  The _mmmm_aaaa_xxxx_llll_eeee_nnnn field is not used
  44.      in _pppp_uuuu_tttt_mmmm_ssss_gggg [see _gggg_eeee_tttt_mmmm_ssss_gggg(2)].  In a similar manner, _d_a_t_a_p_t_r specifies the
  45.      data, if any, to be included in the message.  _f_l_a_g_s indicates what type
  46.      of message should be sent and is described later.
  47.  
  48.      To send the data part of a message, _d_a_t_a_p_t_r must not be _NNNN_UUUU_LLLL_LLLL and the _llll_eeee_nnnn
  49.      field of _d_a_t_a_p_t_r must have a value of 0 or greater.  To send the control
  50.      part of a message, the corresponding values must be set for _c_t_l_p_t_r.  No
  51.      data (control) part is sent if either _d_a_t_a_p_t_r (_c_t_l_p_t_r) is _NNNN_UUUU_LLLL_LLLL or the _llll_eeee_nnnn
  52.      field of _d_a_t_a_p_t_r (_c_t_l_p_t_r) is set to -1.
  53.  
  54.      For _pppp_uuuu_tttt_mmmm_ssss_gggg(), if a control part is specified, and _f_l_a_g_s is set to
  55.      _RRRR_SSSS______HHHH_IIII_PPPP_RRRR_IIII, a high priority message is sent.  If no control part is
  56.      specified, and _f_l_a_g_s is set to _RRRR_SSSS______HHHH_IIII_PPPP_RRRR_IIII, _pppp_uuuu_tttt_mmmm_ssss_gggg fails and sets _eeee_rrrr_rrrr_nnnn_oooo to
  57.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL.  If _f_l_a_g_s is set to 0, a normal (non-priority) message is sent.
  58.      If no control part and no data part are specified, and _f_l_a_g_s is set to 0,
  59.      no message is sent, and 0 is returned.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ppppuuuuttttmmmmssssgggg((((2222))))                                                            ppppuuuuttttmmmmssssgggg((((2222))))
  71.  
  72.  
  73.  
  74.      The stream head guarantees that the control part of a message generated
  75.      by _pppp_uuuu_tttt_mmmm_ssss_gggg is at least 64 bytes in length.
  76.  
  77.      For _pppp_uuuu_tttt_pppp_mmmm_ssss_gggg, the flags are different.  _f_l_a_g_s is a bitmask with the
  78.      following mutually-exclusive flags defined:  _MMMM_SSSS_GGGG______HHHH_IIII_PPPP_RRRR_IIII and _MMMM_SSSS_GGGG______BBBB_AAAA_NNNN_DDDD.  If
  79.      _f_l_a_g_s is set to 0, _pppp_uuuu_tttt_pppp_mmmm_ssss_gggg fails and sets _eeee_rrrr_rrrr_nnnn_oooo to _EEEE_IIII_NNNN_VVVV_AAAA_LLLL.  If a control
  80.      part is specified and _f_l_a_g_s is set to _MMMM_SSSS_GGGG______HHHH_IIII_PPPP_RRRR_IIII and _b_a_n_d is set to 0, a
  81.      high-priority message is sent.  If _f_l_a_g_s is set to _MMMM_SSSS_GGGG______HHHH_IIII_PPPP_RRRR_IIII and either
  82.      no control part is specified or _b_a_n_d is set to a non-zero value,
  83.      _pppp_uuuu_tttt_pppp_mmmm_ssss_gggg() fails and sets _eeee_rrrr_rrrr_nnnn_oooo to _EEEE_IIII_NNNN_VVVV_AAAA_LLLL.  If flags is set to _MMMM_SSSS_GGGG______BBBB_AAAA_NNNN_DDDD,
  84.      then a message is sent in the priority band specified by _b_a_n_d.  If a
  85.      control part and data part are not specified and _f_l_a_g_s is set to
  86.      _MMMM_SSSS_GGGG______BBBB_AAAA_NNNN_DDDD, no message is sent and 0 is returned.
  87.  
  88.      Normally, _pppp_uuuu_tttt_mmmm_ssss_gggg() will block if the stream write queue is full due to
  89.      internal flow control conditions.  For high-priority messages, _pppp_uuuu_tttt_mmmm_ssss_gggg()
  90.      does not block on this condition.  For other messages, _pppp_uuuu_tttt_mmmm_ssss_gggg() does not
  91.      block when the write queue is full and _OOOO______NNNN_DDDD_EEEE_LLLL_AAAA_YYYY or _OOOO______NNNN_OOOO_NNNN_BBBB_LLLL_OOOO_CCCC_KKKK is set.
  92.      Instead, it fails and sets _eeee_rrrr_rrrr_nnnn_oooo to _EEEE_AAAA_GGGG_AAAA_IIII_NNNN.
  93.  
  94.      _pppp_uuuu_tttt_mmmm_ssss_gggg or _pppp_uuuu_tttt_pppp_mmmm_ssss_gggg also blocks, unless prevented by lack of internal
  95.      resources, waiting for the availability of message blocks in the stream,
  96.      regardless of priority or whether _OOOO______NNNN_DDDD_EEEE_LLLL_AAAA_YYYY or _OOOO______NNNN_OOOO_NNNN_BBBB_LLLL_OOOO_CCCC_KKKK has been
  97.      specified.  No partial message is sent.
  98.  
  99.      _pppp_uuuu_tttt_mmmm_ssss_gggg fails if one or more of the following are true:
  100.  
  101.      _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS       _f_i_l_d_e_s is open to a dynamic device, and write permission on
  102.                   the device is denied.
  103.  
  104.      _EEEE_AAAA_GGGG_AAAA_IIII_NNNN       A non-priority message was specified, the _OOOO______NNNN_DDDD_EEEE_LLLL_AAAA_YYYY or
  105.                   _OOOO______NNNN_OOOO_NNNN_BBBB_LLLL_OOOO_CCCC_KKKK flag is set and the stream write queue is full
  106.                   due to internal flow control conditions.
  107.  
  108.      _EEEE_BBBB_AAAA_DDDD_FFFF        _f_d is not a valid file descriptor open for writing.
  109.  
  110.      _EEEE_FFFF_AAAA_UUUU_LLLL_TTTT       _c_t_l_p_t_r or _d_a_t_a_p_t_r points outside the allocated address
  111.                   space.
  112.  
  113.      _EEEE_IIII_NNNN_TTTT_RRRR        A signal was caught during the _pppp_uuuu_tttt_mmmm_ssss_gggg system call.
  114.  
  115.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL       An undefined value was specified in _f_l_a_g_s, or _f_l_a_g_s is set
  116.                   to _RRRR_SSSS______HHHH_IIII_PPPP_RRRR_IIII and no control part was supplied.
  117.  
  118.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL       The stream referenced by _f_d is linked below a multiplexor.
  119.  
  120.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL       For _pppp_uuuu_tttt_pppp_mmmm_ssss_gggg, if _f_l_a_g_s is set to _MMMM_SSSS_GGGG______HHHH_IIII_PPPP_RRRR_IIII and _b_a_n_d is
  121.                   nonzero.
  122.  
  123.      _EEEE_IIII_OOOO          _f_i_l_d_e_s is open to a device that is in the process of
  124.                   closing, or the other end of the pipe is closed.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ppppuuuuttttmmmmssssgggg((((2222))))                                                            ppppuuuuttttmmmmssssgggg((((2222))))
  137.  
  138.  
  139.  
  140.      _EEEE_NNNN_OOOO_SSSS_RRRR        Buffers could not be allocated for the message that was to
  141.                   be created due to insufficient STREAMS memory resources.
  142.  
  143.      _EEEE_NNNN_OOOO_SSSS_TTTT_RRRR       A stream is not associated with _f_d.
  144.  
  145.      _EEEE_NNNN_XXXX_IIII_OOOO        A hangup condition was generated downstream for the
  146.                   specified stream.
  147.  
  148.      _EEEE_RRRR_AAAA_NNNN_GGGG_EEEE       The size of the data part of the message does not fall
  149.                   within the range specified by the maximum and minimum packet
  150.                   sizes of the topmost stream module.  This value is also
  151.                   returned if the control part of the message is larger than
  152.                   the maximum configured size of the control part of a
  153.                   message, or if the data part of a message is larger than the
  154.                   maximum configured size of the data part of a message.
  155.  
  156.      _pppp_uuuu_tttt_mmmm_ssss_gggg also fails if a STREAMS error message had been processed by the
  157.      stream head before the call to _pppp_uuuu_tttt_mmmm_ssss_gggg.  The error returned is the value
  158.      contained in the STREAMS error message.
  159.  
  160. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  161.      _gggg_eeee_tttt_mmmm_ssss_gggg(2), _iiii_nnnn_tttt_rrrr_oooo(2), _pppp_oooo_llll_llll(2), _pppp_uuuu_tttt_mmmm_ssss_gggg(2), _rrrr_eeee_aaaa_dddd(2), _wwww_rrrr_iiii_tttt_eeee(2)
  162.  
  163. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  164.      Upon successful completion, a value of 0 is returned.  Otherwise, a value
  165.      of -1 is returned and _eeee_rrrr_rrrr_nnnn_oooo is set to indicate the error.
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.